openapi: 3.0.1
info:
  title: Test Results API
  description: Provides access to the test results within a Hyperproof organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/testresults
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/testresults
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/testresults
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /mostrecent:
    get:
      summary: Get Most Recent Test Results
      description: >
        `GET /testresults/mostrecent?outcome={outcome}`


        #### Description


        Returns full details of the most recent test results that match the
        specified filter criteria, including outcomes, timestamps, and
        associated objects.
      operationId: get-most-recent-test-results
      parameters:
        - name: outcome
          in: query
          description: Filters results by the provided test outcome
          required: true
          schema:
            enum:
              - passed
              - failed
              - needsReview
              - inRemediation
              - resolved
            type: string
        - name: testParentObjectType
          in: query
          description: >-
            Filters by object type that the test whose results are being
            returned is created on.
          schema:
            enum:
              - control
              - label
              - controlScope
            type: string
        - name: limit
          in: query
          description: The maximum number of test results to return per page.
          schema:
            maximum: 500
            minimum: 1
            type: integer
            default: 50
        - name: nextToken
          in: query
          description: Token returned from a previous call to retrieve test results.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestRunResults'
              example:
                data:
                  - testId: 123e4567-e89b-12d3-a456-426614174000
                    testRunId: 123e4567-e89b-12d3-a456-426614174001
                    outcome: passed
                    testParentObjectType: controlScope
                    testParentObjectId: 123e4567-e89b-12d3-a456-426614174002
                    testCases:
                      - type: object
                        properties:
                          name:
                            type: string
                          condition:
                            type: object
                            properties:
                              arguments:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    argumentType:
                                      type: string
                                    selector:
                                      type: string
                                    operator:
                                      type: string
                                    operand:
                                      type: string
                                  example:
                                    selector: name
                                    operator: '='
                                    operand: John Doe
                            example:
                              arguments:
                                - type: object
                                  properties:
                                    argumentType:
                                      type: string
                                    selector:
                                      type: string
                                    operator:
                                      type: string
                                    operand:
                                      type: string
                                  example:
                                    selector: name
                                    operator: '='
                                    operand: John Doe
                          results:
                            type: object
                            properties:
                              rowResults:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    row:
                                      type: integer
                                    argumentResults:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          value:
                                            type: string
                                          errorInfo:
                                            type: string
                                            description: Details on the failure
                                          operandValue:
                                            type: string
                                            description: >-
                                              The value that the proof value was
                                              compared against.
                                        example:
                                          value: John Doe
                                  example:
                                    row: 1
                                    argumentResults:
                                      - type: object
                                        properties:
                                          value:
                                            type: string
                                          errorInfo:
                                            type: string
                                            description: Details on the failure
                                          operandValue:
                                            type: string
                                            description: >-
                                              The value that the proof value was
                                              compared against.
                                        example:
                                          value: John Doe
                              thresholdResult:
                                type: object
                                properties:
                                  rowsTested:
                                    type: integer
                                  passPercentage:
                                    type: number
                                    format: float
                                  evaluationThreshold:
                                    type: number
                                    format: float
                                example:
                                  rowsTested: 100
                                  passPercentage: 95
                                  evaluationThreshold: 80
                        example:
                          name: Example Test Case Name
                          condition:
                            type: object
                            properties:
                              arguments:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    argumentType:
                                      type: string
                                    selector:
                                      type: string
                                    operator:
                                      type: string
                                    operand:
                                      type: string
                                  example:
                                    selector: name
                                    operator: '='
                                    operand: John Doe
                            example:
                              arguments:
                                - type: object
                                  properties:
                                    argumentType:
                                      type: string
                                    selector:
                                      type: string
                                    operator:
                                      type: string
                                    operand:
                                      type: string
                                  example:
                                    selector: name
                                    operator: '='
                                    operand: John Doe
                          results:
                            rowResults:
                              - type: object
                                properties:
                                  row:
                                    type: integer
                                  argumentResults:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        value:
                                          type: string
                                        errorInfo:
                                          type: string
                                          description: Details on the failure
                                        operandValue:
                                          type: string
                                          description: >-
                                            The value that the proof value was
                                            compared against.
                                      example:
                                        value: John Doe
                                example:
                                  row: 1
                                  argumentResults:
                                    - type: object
                                      properties:
                                        value:
                                          type: string
                                        errorInfo:
                                          type: string
                                          description: Details on the failure
                                        operandValue:
                                          type: string
                                          description: >-
                                            The value that the proof value was
                                            compared against.
                                      example:
                                        value: John Doe
                            thresholdResult:
                              type: object
                              properties:
                                rowsTested:
                                  type: integer
                                passPercentage:
                                  type: number
                                  format: float
                                evaluationThreshold:
                                  type: number
                                  format: float
                              example:
                                rowsTested: 100
                                passPercentage: 95
                                evaluationThreshold: 80
                nextToken: string
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            testresult.read: Grants read access to testresults
  schemas:
    ArgumentResult:
      type: object
      properties:
        value:
          type: string
          description: The value resulting from the argument evaluation.
        errorInfo:
          type: string
          description: Details on the failure.
        operandValue:
          type: string
          description: The value that the proof value was compared against.
      example:
        value: John Doe
    ConditionArgument:
      type: object
      properties:
        argumentType:
          type: string
          description: The type of argument in the condition.
        selector:
          type: string
          description: The selector for the condition argument.
        operator:
          type: string
          description: The operator used in the condition (e.g., equals).
        operand:
          type: string
          description: The operand value in the condition.
      example:
        selector: name
        operator: '='
        operand: John Doe
    RowResult:
      type: object
      properties:
        row:
          type: integer
          description: The row number of the result.
        argumentResults:
          type: array
          description: The list of argument results for the row.
          items:
            $ref: '#/components/schemas/ArgumentResult'
      example:
        row: 1
        argumentResults:
          - $ref: '#/components/schemas/ArgumentResult'
    TestCaseCondition:
      type: object
      properties:
        arguments:
          type: array
          description: The list of arguments for the test case condition.
          items:
            $ref: '#/components/schemas/ConditionArgument'
      example:
        arguments:
          - $ref: '#/components/schemas/ConditionArgument'
    TestCaseResult:
      type: object
      properties:
        name:
          type: string
          description: The name of the test case result.
        condition:
          $ref: '#/components/schemas/TestCaseCondition'
        results:
          type: object
          properties:
            rowResults:
              type: array
              description: The results of the test case.
              items:
                $ref: '#/components/schemas/RowResult'
            thresholdResult:
              $ref: '#/components/schemas/ThresholdResult'
      example:
        name: Example Test Case Name
        condition:
          $ref: '#/components/schemas/TestCaseCondition'
        results:
          rowResults:
            - $ref: '#/components/schemas/RowResult'
          thresholdResult:
            $ref: '#/components/schemas/ThresholdResult'
    TestRunResult:
      type: object
      properties:
        testId:
          type: string
          description: The unique identifier of the test.
          format: uuid
        testRunId:
          type: string
          description: The unique identifier of the test run.
          format: uuid
        outcome:
          type: string
          description: The outcome of the test run.
        testParentObjectType:
          type: string
          description: The parent object type of the test.
        testParentObjectId:
          type: string
          description: The parent object identifier of the test.
          format: uuid
        testCases:
          type: array
          description: The list of test cases in the run.
          items:
            $ref: '#/components/schemas/TestCaseResult'
      example:
        testId: 123e4567-e89b-12d3-a456-426614174000
        testRunId: 123e4567-e89b-12d3-a456-426614174001
        outcome: passed
        testParentObjectType: controlScope
        testParentObjectId: 123e4567-e89b-12d3-a456-426614174002
        testCases:
          - $ref: '#/components/schemas/TestCaseResult'
    TestRunResults:
      type: object
      properties:
        data:
          type: array
          description: The data in the test run results.
          items:
            $ref: '#/components/schemas/TestRunResult'
        nextToken:
          type: string
          description: The token for the next page of test run results.
    ThresholdResult:
      type: object
      properties:
        rowsTested:
          type: integer
          description: The number of rows tested.
        passPercentage:
          type: number
          description: The pass percentage in the result.
          format: float
        evaluationThreshold:
          type: number
          description: The evaluation threshold in the result.
          format: float
      example:
        rowsTested: 100
        passPercentage: 95
        evaluationThreshold: 80
